<?php

namespace Illuminate\Contracts\Filesystem;

/**
 * 文件系统接口定义
 */
interface Filesystem
{
    /**
     * 文件公开可见权限标识
     *
     * @var string
     */
    const VISIBILITY_PUBLIC = 'public';

    /**
     * 文件私有可见权限标识
     *
     * @var string
     */
    const VISIBILITY_PRIVATE = 'private';

    /**
     * 确认文件是否存在
     *
     * @param  string $path 文件路径
     * @return bool
     */
    public function exists($path);

    /**
     * 获取一个文件的全部内容，并返回字符串
     *
     * @param  string $path 文件路径
     * @return string
     *
     * @throws \Illuminate\Contracts\Filesystem\FileNotFoundException
     */
    public function get($path);

    /**
     * 获取一个文件的 resource 对象
     *
     * @param  string $path 文件路径
     * @return resource|null 指定文件打开失败时，返回 null
     *
     * @throws \Illuminate\Contracts\Filesystem\FileNotFoundException
     */
    public function readStream($path);

    /**
     * 写入给定的内容到文件中
     *
     * @param  string $path 文件路径
     * @param  string|resource $contents 写入内容
     * @param  mixed $options 写入选项
     * @return bool 是否写入成功
     */
    public function put($path, $contents, $options = []);

    /**
     * 把一个 resource 对象的内容，全部写入到文件中
     *
     * @param  string $path 文件路径
     * @param  resource $resource 资源对象
     * @param  array $options 写入选项
     * @return bool 是否写入成功
     *
     * @throws \InvalidArgumentException If $resource is not a file handle.
     * @throws \Illuminate\Contracts\Filesystem\FileExistsException
     */
    public function writeStream($path, $resource, array $options = []);

    /**
     * 获取指定文件的可见性
     *
     * @param  string $path 文件路径
     * @return string 可见性标识
     */
    public function getVisibility($path);

    /**
     * 设置指定文件的可见性
     *
     * @param  string $path 文件路径
     * @param  string $visibility 可见性标识
     * @return bool 是否设置成功
     */
    public function setVisibility($path, $visibility);

    /**
     * 把给定的内容增加到文件头部
     *
     * @param  string $path 文件路径
     * @param  string $data 追加内容
     * @return bool 是否追加成功
     */
    public function prepend($path, $data);

    /**
     * 把给定的内容追加到文件尾部
     *
     * @param  string $path 文件路径
     * @param  string $data 追加内容
     * @return bool 是否追加成功
     */
    public function append($path, $data);

    /**
     * 删除指定的文件或目录，可同时删除多个文件
     *
     * @param  string|array $paths 文件路径 | 文件路径数组
     * @return bool 是否删除成功
     */
    public function delete($paths);

    /**
     * 复制一个文件到新的位置
     *
     * @param  string $from 文件原路径
     * @param  string $to 文件新路径
     * @return bool 是否复制成功
     */
    public function copy($from, $to);

    /**
     * 移动一个文件到新的位置
     *
     * @param  string $from 文件原路径
     * @param  string $to 文件新路径
     * @return bool 是否移动成功
     */
    public function move($from, $to);

    /**
     * 获取指定文件的大小
     *
     * @param  string $path 文件路径
     * @return int
     */
    public function size($path);

    /**
     * 得到指定文件的最后修改时间
     *
     * @param  string $path 文件路径
     * @return int 时间戳
     */
    public function lastModified($path);

    /**
     * 获取一个目录中的所有文件
     *
     * @param  string|null $directory 目录路径
     * @param  bool $recursive 是否循环递归子目录
     * @return array
     */
    public function files($directory = null, $recursive = false);

    /**
     * 获取指定目录中的所有文件（递归子目录）
     *
     * @param  string|null $directory 目录路径
     * @return array
     */
    public function allFiles($directory = null);

    /**
     * 获取指定目录中所有的子目录
     *
     * @param  string|null $directory 目录路径
     * @param  bool $recursive 是否递归子目录
     * @return array
     */
    public function directories($directory = null, $recursive = false);

    /**
     * 获取给定目录中的所有（递归）目录。
     *
     * @param  string|null $directory 目录路径
     * @return array
     */
    public function allDirectories($directory = null);

    /**
     * 创建一个目录
     *
     * @param  string $path 目录路径
     * @return bool
     */
    public function makeDirectory($path);

    /**
     * 递归删除一个目录
     *
     * @param  string $directory 目录路径
     * @return bool
     */
    public function deleteDirectory($directory);
}
